Redesign WSL gateway setup and OpenClaw onboard UX by bkudiess · Pull Request #792 · openclaw/openclaw-windows-node

bkudiess · 2026-06-19T20:05:19Z

Summary

Problem: The WSL gateway setup flow did not clearly show what OpenClaw installs, which Windows permissions/capabilities apply, or what is happening during setup and onboard recovery.
Why it matters: Power users need transparency and recovery context without adding extra clicks for the common path.
What changed: Reworked setup into a Windows-native WinUI flow: security notice, setup choice, capability/permission/install review, setup progress, gateway-installed milestone, OpenClaw onboard transcript, and updated complete/error states.
User impact: Users see the selected capability profile, relevant Windows permission status, install details, progress, recovery actions, and a clear handoff before OpenClaw onboard. Launch at startup now defaults on intentionally so OpenClaw is ready after reboot; users can turn it off on the final screen.
What did NOT change (scope boundary): Install pipeline steps, gateway protocol, credential model, pairing protocol, and node/MCP command contracts are unchanged.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related #
Related to a bug or regression

Validation

Required closeout:

.\build.ps1 ✅
dotnet test .\tests\OpenClaw.SetupEngine.Tests\\OpenClaw.SetupEngine.Tests.csproj --no-restore ✅ 363 passed
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore ✅ 2686 passed, 31 skipped
dotnet test .\tests\OpenClaw.Tray.Tests\\OpenClaw.Tray.Tests.csproj --no-restore ✅ 1454 passed

Additional sweep:

dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj ✅ 376 passed
dotnet test .\tests\OpenClaw.WinNode.Cli.Tests\OpenClaw.WinNode.Cli.Tests.csproj ✅ 120 passed
dotnet test .\tests\OpenClawTray.FunctionalUI.Tests\OpenClawTray.FunctionalUI.Tests.csproj ✅ 10 passed
dotnet test .\tests\OpenClaw.Tray.UITests\OpenClaw.Tray.UITests.csproj -r win-arm64 ✅ 76 passed
dotnet test .\tests\OpenClaw.E2ETests\OpenClaw.E2ETests.csproj ✅ 20 skipped (real-gateway gated)
dotnet test .\tests\OpenClaw.Tray.IntegrationTests\OpenClaw.Tray.IntegrationTests.csproj ✅ 18 skipped (integration-gated)

Real behavior proof

Environment tested: Windows ARM64, Debug win-arm64, isolated tray data.
PR head / commit tested: 2ca2d214.
Exact steps or command run:

.\build.ps1
$env:OPENCLAW_FORCE_ONBOARDING="1"
.\run-app-local.ps1 -NoBuild -Isolated -AllowNonMain

Observed result: Flow shows the new native setup sequence, inline permissions/install review, collapsed live activity, gateway-installed handoff before onboard, transcript-style onboard, More options recovery, and mascot corner-badge complete states.
Screenshot/artifact links verified? Existing uploaded links preserved; CLI HEAD requests to github.com/user-attachments returned 403 in this environment, so browser-side verification is not re-claimed here.
Not verified / blocked: Real gateway E2E tests are gated/skipped without real-gateway environment variables; integration suites report expected gated skips.

Security Impact (required)

New permissions/capabilities? No — no new capability or OS permission surface added.
Secrets/tokens handling changed? No.
New/changed network calls? No.
Command/tool execution surface changed? No.
Data access scope changed? Yes — default capability profile is now Standard instead of silently inheriting the prior full default; users can still choose Full access before install.
If any Yes, explain risk + mitigation: The default is intentionally more explicit and reviewable. The capability profile, relevant Windows permissions, and install review are visible before setup runs.

Compatibility / Migration

Backward compatible? Yes.
Config/env changes? No.
Migration needed? No.
If yes, exact upgrade steps: N/A.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only conversations that still need reviewer or maintainer judgment.

Rubber-duck review

Final rubber-duck/Hanselman reviews found no blocking issues after fixes. Follow-up cleanups from review were applied: stale Lobster attribution/wording removed, old V2 preview artifacts deleted, direct onboard lock-contention path now surfaces inline feedback, the milestone feedback is a live region for accessibility, selected capability profiles persist into runtime Node* settings, completion persists only AutoStart, direct onboard starts at the milestone without flashing the security page, direct onboard preserves existing startup preferences, and permission-status probe failures show inline warning UI.

clawsweeper · 2026-06-19T20:06:09Z

Codex review: needs real behavior proof before merge. Reviewed July 1, 2026, 1:08 AM ET / 05:08 UTC.

Summary
The PR redesigns the WSL gateway setup and OpenClaw onboard flow with new setup screens, capability/profile review, updated branding/assets/docs, and setup/runtime settings persistence changes.

Reproducibility: yes. from source inspection: open direct OpenClaw onboard, complete the hidden startup-preference flow, and the hidden child toggle can still supply enableAutoStart: true to the tray restart path. No live Windows run was performed in this read-only review.

Review metrics: 2 noteworthy metrics.

Diff surface: 75 files; +1984/-3937. The PR spans setup pages, tray handoff code, settings persistence, binary assets, docs, tests, and deleted preview tooling, so broad review and proof matter.
Proof coverage: 11 screenshots; 0 restart/runtime artifacts. Screenshots help visual review but do not prove changed capability/startup settings survive restart or govern the running node.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🦪 silver shellfish
Patch quality: 🧂 unranked krab
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P1] Fix the direct-onboard AutoStart propagation bug and add a focused test.
[P1] Add current-head redacted runtime/settings proof after restart.
[P1] Add real-gateway install/onboard/working-node proof or a precise blocker.

Proof guidance:

[P1] Needs stronger real behavior proof before merge: The PR body includes screenshots of the visible flow, but the links were not inspectable here and the proof does not show restart persistence, runtime capability enforcement, or a real-gateway path; add redacted logs/output/recording and update the PR body for re-review.

Mantis proof suggestion
After the code blocker is fixed, a Windows visual proof pass with diagnostics would materially help verify the redesigned setup flow and startup/capability persistence. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify the redesigned WSL gateway setup flow and capture redacted settings/runtime evidence that selected capability profile and startup choice survive restart.

Risk before merge

[P1] Direct OpenClaw onboard can still enable Windows startup despite hiding the startup preference, overriding an existing disabled startup choice during re-onboard.
[P1] The PR changes first-run setup defaults around startup-on and Standard capability profile, so maintainers need to explicitly accept the product/compatibility direction before merge.
[P1] The current proof is visual-first and does not demonstrate restart persistence, runtime capability enforcement, or a working real-gateway install/onboard/node path.

Maintainer options:

Fix AutoStart propagation before merge (recommended)
Ensure hidden-startup-preference direct onboard sessions cannot pass a synthetic true value into tray restart/autostart, and add a focused contract test for preserving an existing disabled startup choice.
Require runtime proof after the fix
Ask for redacted terminal/log/settings output or a recording proving capability profile and startup behavior after restart plus real-gateway install/onboard evidence or a precise blocker.
Pause under the local-gateway epic
If the startup-on and Standard-profile defaults are still unsettled product direction, keep this PR paused until the broader local-gateway tracking work clarifies first-run behavior.

Next step before merge

[P1] The PR needs a contributor/maintainer fix for a narrow AutoStart compatibility bug plus contributor-supplied runtime proof, so this should stay in human review rather than an automated repair lane.

Security
Cleared: No concrete code-level security or supply-chain regression was found; the remaining security-boundary concern is missing runtime proof for capability restrictions.

Review findings

[P1] Preserve AutoStart when hiding the startup choice — src/OpenClaw.SetupEngine.UI/Pages/CompletePage.xaml.cs:32-33

Review details

Best possible solution:

Fix the direct-onboard AutoStart propagation bug, add focused regression coverage, then merge only after maintainers accept the changed defaults and the PR body includes current-head runtime/gateway proof or a clear environment blocker.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection: open direct OpenClaw onboard, complete the hidden startup-preference flow, and the hidden child toggle can still supply enableAutoStart: true to the tray restart path. No live Windows run was performed in this read-only review.

Is this the best way to solve the issue?

No: the latest implementation skips settings-file persistence for direct onboard, but it still allows the tray restart handler to enable Windows startup from the hidden toggle value. The narrower solution is to make hidden-startup-preference completions pass false or preserve the existing setting through the whole completion path.

Full review comments:

[P1] Preserve AutoStart when hiding the startup choice — src/OpenClaw.SetupEngine.UI/Pages/CompletePage.xaml.cs:32-33
For direct OpenClaw onboard, SetupWindow hides StartupRow, but LaunchButton_Click still computes enableAutoStart from StartupToggle.Visibility and IsOn. A collapsed parent does not change the child toggle's own Visibility, and the toggle is seeded on, so the tray handler can still receive true and enable Windows startup even for users who previously disabled it. Gate completion on the same hidden-preference state or pass the existing preference instead.
Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.88

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 4166e0fd63f8.

Label changes

Label changes:

add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦪 silver shellfish and patch quality is 🧂 unranked krab.
remove rating: 🦪 silver shellfish: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.

Label justifications:

P2: This is a substantial setup/onboarding improvement PR with a merge-blocking compatibility defect, but it is not an already-shipped emergency regression.
merge-risk: 🚨 compatibility: Merging this PR as-is could change existing Windows startup behavior during direct OpenClaw onboard and changes setup defaults.
merge-risk: 🚨 security-boundary: The PR changes how capability restrictions are selected and persisted, so runtime enforcement proof is needed before maintainers rely on the new boundary.
rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦪 silver shellfish and patch quality is 🧂 unranked krab.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR body includes screenshots of the visible flow, but the links were not inspectable here and the proof does not show restart persistence, runtime capability enforcement, or a real-gateway path; add redacted logs/output/recording and update the PR body for re-review.
proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body includes screenshots of the visible flow, but the links were not inspectable here and the proof does not show restart persistence, runtime capability enforcement, or a real-gateway path; add redacted logs/output/recording and update the PR body for re-review.

Evidence reviewed

What I checked:

Repository policy applied: AGENTS.md was read fully; its setup/onboarding proof policy and App.xaml.cs guardrails apply because this PR changes tray-hosted setup UX, direct onboarding, permissions, and setup defaults. (AGENTS.md:31, 4166e0fd63f8)
Current main lacks central redesign: Current main still opens setup directly at WelcomePage, so the redesigned security notice and setup/onboard flow are not already implemented in the latest release SHA. (src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs:91, 4166e0fd63f8)
PR head changes setup entry flow: PR head starts fresh setup at SecurityNoticePage and direct onboarding at the gateway-installed milestone. (src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs:106, 2ca2d2146114)
Direct onboard hides startup preference only in setup window state: PR head disables startup preference persistence and visibility for direct onboard, but RequestSetupCompleted still invokes the tray handler with the enableAutoStart argument it receives. (src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs:77, 2ca2d2146114)
Hidden row still feeds enabled toggle value: CompletePage hides StartupRow, but LaunchButton_Click computes enableAutoStart from the child StartupToggle's own Visibility and IsOn values; the child remains logically Visible and is seeded on. (src/OpenClaw.SetupEngine.UI/Pages/CompletePage.xaml.cs:32, 2ca2d2146114)
Tray restart enables autostart from event argument: The tray restart path calls AutoStartManager.SetAutoStartAsync(true) whenever the setup completion event argument is true, so the hidden-toggle value can still change Windows startup behavior. (src/OpenClaw.Tray.WinUI/App.xaml.cs:3692, 2ca2d2146114)

Likely related people:

ranjeshj: History ties Ranjesh to the out-of-process SetupEngine and tray-hosted setup integration that this PR redesigns. (role: setup engine feature introducer; confidence: high; commits: cefce3952ab1, afa6218338d6, 429be9ba9368; files: src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs, src/OpenClaw.SetupEngine/SetupContext.cs, src/OpenClaw.Tray.WinUI/App.xaml.cs)
bkudiess: Current-main history shows Barbara Kudiess working on richer gateway wizard handling and WSL dependency recovery in the same setup/onboard area, beyond authoring this PR. (role: recent setup wizard contributor; confidence: high; commits: 84d2e6ab80c8, 1e6951331f1c, b90ded9a5eea; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine/SetupWizardRunner.cs, docs/ONBOARDING_WIZARD.md)
shanselman: Recent commits by Scott Hanselman added setup triage fixes, App refactor guardrails, and validation around the broad tray/setup surface this PR touches. (role: recent setup validation and guardrail contributor; confidence: medium; commits: ad943b9e6fd8, 06b63ac6ce7d, 4166e0fd63f8; files: AGENTS.md, tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs, src/OpenClaw.Tray.WinUI/App.xaml.cs)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Remove stale setup screenshots, delete the unused tray SetupWizardWindow and obsolete SetupEngine permissions page, and route direct OpenClaw onboard entry points through the new gateway-installed handoff so users keep the redesigned setup context. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Expose preview-only setup error and OpenClaw onboard error states so the PR screenshot set can cover the recovery UI without checking image artifacts into the repo. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Use the OpenClaw mascot with a corner success badge for the setup complete state, matching the gateway-installed and setup-failed visual language. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Delete the abandoned Onboarding V2 preview harness and visual-diff assets, remove stale lobster branding references, and harden the gateway-installed handoff with inline feedback if onboarding cannot start immediately. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Persist capability profile selections into the runtime node settings used after tray restart, and save the final launch-at-startup choice before restarting the tray. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Ensure capability profile selections are written to the runtime Node* settings used after restart, and persist only the final startup preference when setup completes so direct onboard does not reset existing capability choices. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Start direct onboard windows directly at the gateway-installed handoff and surface permission status read failures inline so setup never silently degrades. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

bkudiess · 2026-07-01T03:04:35Z

@clawsweeper re-review

clawsweeper · 2026-07-01T03:04:39Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Hide and skip persisting the startup preference for direct OpenClaw onboard sessions so existing AutoStart choices are not overwritten, while fresh setup still defaults startup on. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

bkudiess · 2026-07-01T04:52:04Z

@clawsweeper re-review

clawsweeper · 2026-07-01T04:52:07Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

bkudiess force-pushed the bkudiess/onboarding-ux-audit branch from e2f2f28 to 5e5a0e3 Compare June 23, 2026 06:51

bkudiess changed the base branch from master to main June 23, 2026 06:51

bkudiess force-pushed the bkudiess/onboarding-ux-audit branch from 5e5a0e3 to 6d89068 Compare June 27, 2026 23:36

Copilot and others added 4 commits June 30, 2026 16:06

Add preview coverage for onboarding error states

eb642ff

Expose preview-only setup error and OpenClaw onboard error states so the PR screenshot set can cover the recovery UI without checking image artifacts into the repo. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Use mascot status badge on complete screen

f750fbb

Use the OpenClaw mascot with a corner success badge for the setup complete state, matching the gateway-installed and setup-failed visual language. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

bkudiess changed the title ~~Redesign WSL gateway onboarding (stepped, brand-themed, accessible)~~ Redesign WSL gateway setup and OpenClaw onboard UX Jul 1, 2026

bkudiess marked this pull request as ready for review July 1, 2026 01:51

clawsweeper Bot added proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. and removed proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. labels Jul 1, 2026

Copilot and others added 2 commits June 30, 2026 19:00

Persist setup profile and startup choices

c87aa34

Persist capability profile selections into the runtime node settings used after tray restart, and save the final launch-at-startup choice before restarting the tray. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. labels Jul 1, 2026

Polish onboarding review edge cases

57999d9

Start direct onboard windows directly at the gateway-installed handoff and surface permission status read failures inline so setup never silently degrades. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Jul 1, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Redesign WSL gateway setup and OpenClaw onboard UX#792

Redesign WSL gateway setup and OpenClaw onboard UX#792
bkudiess wants to merge 11 commits into
openclaw:mainfrom
bkudiess:bkudiess/onboarding-ux-audit

bkudiess commented Jun 19, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

bkudiess commented Jul 1, 2026

Uh oh!

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

bkudiess commented Jul 1, 2026

Uh oh!

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

bkudiess commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Validation

Real behavior proof

Security Impact (required)

Compatibility / Migration

Review Conversations

Rubber-duck review

Uh oh!

clawsweeper Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bkudiess commented Jul 1, 2026

Uh oh!

clawsweeper Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bkudiess commented Jul 1, 2026

Uh oh!

clawsweeper Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

bkudiess commented Jun 19, 2026 •

edited

Loading

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading